'\" te
.\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (C) 1997, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LDAPSEARCHPREFS.CONF 5 "Nov 26, 2017"
.SH NAME
ldapsearchprefs.conf \- configuration file for LDAP search preference routines
.SH SYNOPSIS
.LP
.nf
\fB/etc/opt/SUNWconn/ldap/current/ldapsearchprefs.conf\fR
.fi

.SH DESCRIPTION
.LP
The \fBldapsearchprefs.conf\fR file contains information used by LDAP when
searching the directory. Blank lines and lines that start with a hash ('#')
character are treated as comments and ignored. Non-comment lines contain one or
more tokens. Tokens are separated by white space, and double quotes can be used
to include white space inside a token.
.sp
.LP
Search preferences are typically used by LDAP-based client programs to specify
what a user may search for, which attributes are searched, and which options
are available to the user.
.sp
.LP
The first non-comment line specifies the version of the template information
and must contain the token \fBVersion\fR followed by an integer version number.
For example:
.sp
.in +2
.nf
Version 1
.fi
.in -2
.sp

.sp
.LP
The current version is \fI1,\fR so the above example is always the correct
opening line.
.sp
.LP
The remainder of the file consists of one or more search preference
configurations. The first line of a search preference is a human-readable name
for the type of object being searched for, for example \fBPeople\fR or
\fBOrganizations\fR. This name is stored in the \fIso_objtypeprompt\fR member
of the \fBldap_searchobj\fR structure (see \fBldap_searchprefs\fR(3LDAP)). For
example:
.sp
.in +2
.nf
People
.fi
.in -2
.sp

.sp
.LP
specifies a label for a search preference designed to find X.500 entries for
people.
.sp
.LP
The next line specifies a list of options for this search object. The only
option currently allowed is "internal" which means that this search object
should not be presented directly to a user. Options are placed in the
\fIso_options\fR member of the \fIldap_searchobj\fR structure and can be tested
using the \fBLDAP_IS_SEARCHOBJ_OPTION_SET()\fR macro. Use "" if no special
options are required.
.sp
.LP
The next line specifies a label to use for "Fewer Choices" searches. "Fewer
Choices" searches are those where the user's input is fed to the ldap_filter
routines to determine an appropriate filter to use. This contrasts with
explicitly-constructed LDAP filters, or "More Choices" searches, where the user
can explicitly construct an LDAP filter.
.sp
.LP
For example:
.sp
.in +2
.nf
"Search For:"
.fi
.in -2
.sp

.sp
.LP
can be used by LDAP client programs to label the field into which the user can
type a "Fewer Choices" search.
.sp
.LP
The next line specifies an LDAP filter prefix to append to all "More Choices"
searched. This is typically used to limit the types of entries returned to
those containing a specific object class. For example:
.sp
.in +2
.nf
"(&(objectClass=person)"
.fi
.in -2
.sp

.sp
.LP
would cause only entries containing the object class \fIperson\fR to be
returned by a search. Note that parentheses may be unbalanced here, since this
is a filter prefix, not an entire filter.
.sp
.LP
The next line is an LDAP filter tag which specifies the set of LDAP filters to
be applied for "Fewer Choices" searching. The line
.sp
.in +2
.nf
\fB"x500-People"\fR
.fi
.in -2
.sp

.sp
.LP
would tell the client program to use the set of LDAP filters from the ldap
filter configuration file tagged "x500-People".
.sp
.LP
The next line specifies an LDAP attribute to retrieve to help the user choose
when several entries match the search terms specified. For example:
.sp
.in +2
.nf
"title"
.fi
.in -2
.sp

.sp
.LP
specifies that if more than one entry matches the search criteria, the client
program should retrieve the \fBtitle\fR attribute that and present that to the
user to allow them to select the appropriate entry. The next line specifies a
label for the above attribute, for example,
.sp
.in +2
.nf
"Title:"
.fi
.in -2
.sp

.sp
.LP
Note that the values defined so far in the file are defaults, and are intended
to be overridden by the specific search options that follow.
.sp
.LP
The next line specifies the scope of the LDAP search to be performed.
Acceptable values are subtree, onelevel, and base.
.sp
.LP
The next section is a list of "More Choices" search options, terminated by a
line containing only the string \fBEND\fR. For example:
.sp
.in +2
.nf
"Common Name"	cn	11111	""	""
"Surname"	sn	11111	""	""
"Business Phone"	"telephoneNumber"	11101	""	""
END
.fi
.in -2
.sp

.sp
.LP
 Each line represents one method of searching. In this example, there are three
ways of searching - by Common Name, by Surname, and by Business Phone number.
The first field is the text which should be displayed to user. The second field
is the attribute which will be searched. The third field is a bitmap which
specifies which of the match types are permitted for this search type. A "1"
value in a given bit position indicates that a particular match type is valid,
and a "0" indicates that is it not valid. The fourth and fifth fields are,
respectively, the select attribute name and on-screen name for the selected
attribute. These values are intended to override the defaults defined above. If
no specific values are specified, the client software uses the default values
above.
.sp
.LP
The next section is a list of search match options, terminated by a a line
containing only the string \fBEND\fR. Example:
.sp
.in +2
.nf
"exactly matches"	"(%a=%v))"
"approximately matches"	"(%a~=%v))"
"starts with"	"(%a=%v*))"
"ends with"	"(%a=*%v))"
"contains"	"(%a=*%v*))"
END
.fi
.in -2
.sp

.sp
.LP
In this example, there are five ways of refining the search. For each method,
there is an LDAP filter suffix which is appended to the ldap filter.
.SH EXAMPLES
.LP
\fBExample 1 \fRA Sample Configuration Using Search Preference for "people"
.sp
.LP
The following example illustrates one possible configuration of search
preferences for "people".

.sp
.in +2
.nf
# Version number
Version 1
# Name for this search object
People
# Label to place before text box user types in
"Search For:"
# Filter prefix to append to all "More Choices" searches
"(&(objectClass=person)"
# Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
"x500-People"
# If a search results in > 1 match, retrieve this attribute to help
# user distinguish between the entries...
multilineDescription
# ...and label it with this string:
"Description"
# Search scope to use when searching
subtree
# Follows a list of "More Choices" search options. Format is:
# Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
# If last two are null, "Fewer Choices" name/attributes used
"Common Name"                   cn                 11111  ""  ""
"Surname"                       sn                 11111  ""  ""
"Business Phone"                "telephoneNumber"  11101  ""  ""
"E-Mail Address"                "mail"             11111  ""  ""
"Uniqname"                      "uid"              11111  ""  ""
END
# Match types
"exactly matches"               "(%a=%v))"
"approximately matches"         "(%a~=%v))"
"starts with"                   "(%a=%v*))"
"ends with"                     "(%a=*%v))"
"contains"                      "(%a=*%v*))"
END
.fi
.in -2

.sp
.LP
In this example, the user may search for People. For "fewer choices" searching,
the tag for the \fBldapfilter.conf\fR(5) file is "x500-People".
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
Stability Level	Evolving
.TE

.SH SEE ALSO
.LP
.BR ldap_searchprefs (3LDAP),
.BR attributes (7)
